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HOW TO 


How to Use This Guide 


This guide is designed to provide a description 
of those PLAN 4000 network functions that are 
specific to the Apple /// SOS environment. 


When familiarizing yourself with the PLAN 4000 
system, read first the General Information 
Manual. 


For information pertaining to your networks 
file servers, which allow you to share hard disk 
storage with other network users, read the File 
Server Users Manual. A bibliography of PLAN 
4000 system manuals and guides appears at the: 
end of this guide. 


The material in this document applies to Version 
2.0 of the File Server software. A 


We welcome criticisms and suggestions. Forms for 
reporting program errors, documentation errors, 
or inadequacies are provided at the back of this 
manual. 


4/ 1/83 iii 


CONTENTS 


Contents 
Disclaimer... ...e e eeeooeococococeceecceece ii 
How to Use This Guide "n" iii 
ContentS.....eccoccoccceccceeceeeeececceeccse V 
Chapter 1 Starting Up 


1.0 IntrodüctlOoOu i429» 4»»9»»» del 
1.1 Starting Upsssesoseeeeseesoeesoeeseoee Im] 
1.2 Network DeviceS..-ssoeoseseeeoeoeeeeee lel 
1.3 A Boot Diskette for Network Use...... 1-2 
1.4 Booting Your Apple /// Workstation... 1-4 


Chapter 2 Using the Network 


2.0 Shared Disk Organization: Virtual 
Volume NameS. sesse eeoeeooeooocccecs 2—l 
Virtual Diskettes of Variable Size... 2-2 
File Server Commands:The NET Program. 2-4 
Creating Virtual Diskettes........... 2-77 
Using Virtual Diskettes in SOS....... 2-8 
Using Virtual Drives..........e.ce e^. 2-10 
Local NET Commands........ e.c eee eo oe e» 2-11 
Other NET Inputs and Commands........ 2-14 
Multiple File Servers and Multiple 
NetwOrkSe..o«ecocccececceccceccceecce dels 
2.9 Network Virtual Spooled Printer...... 2-18 
2.10 Running Programs in Protected 

Environment .cccscccccccccccccessecss 2719 
2.11 Capturing Apple /// Basic Files As 

ASCII Text FileS.ssssosseesesseeseeee 2-19 


R2 OPO I IO. I. I2 B9 


CON OD UWI p- W Nym 


Chapter 3 Programming 


3.1 Using File Server Commands Within A 


4/1/83 | V 


CONTENTS 


Pascal Programecccccccccecvcecccecses IML 
3.2 A Sample Program. esecsesoesseososoeoee Sef 
3.3 The SOS Basic Environment.ssssesseeese 3-8 
3.4 Apple // Compatibility.sseseseeeeeeee 3-9 
3.5 Reading a Station Number from Within 
a Program. .sssesoeeeeeossoeseseeseeee 379 
.6 The Nestar CVAL Conventionssssseeseee 3-10 
7 The SOS Network Drivers: 
Advanced Device Information.......... 3-14 
Device Configuration Block........... 3-15 
Device Driver Calls....... esee ooo 3-18 
O The .NMSG Device Driver Calls........ 3-19 
1 The NI ... N11 Device Driver Calls. 3-20 
2 Device Identification Codes.......... 3-22 


Chapter 4 Utility Programs 


4.0 Network Utility ProgramS.s-eeseeeoeeoe 4-1 
4.1 STARTUP ee*e€e600e(060060060060090006€000060€06060€699€9 4-2 
4 2 TREEWALK. ee oe ee ese eeeeooeoeeeoeseeeoe 4-7 


Appendices 


A Error and Information Messages....... AL 
B File Server CommandS.. see eeeeeeseee B-1 


Index 
Bibliography . 


Reader Comment Form 


vi — 4/1/83 


STARTUP 


Chapter 1 


Starting Up 


1.0 Introduction 


This guide assumes that you are familiar with 
the Apple /// machine, with SOS, and with the 
PLAN 4000 network as described in the General 
Information Manual and the File Server User^s 
Manual. 


1.1 Starting Up 


Apple /// users boot by inserting a minidiskette 
in their built-in minidisk drive. The diskette 
is formatted for Apple SOS, and will load the 
interpreter and operating system that it 
contains (Pascal, Visicalc  (R), PFS (R), 
Business Basic, etc.). | 


PLAN 4000 Apple /// Network Interface cards will 
not work in Apple // DOS emulation mode. 


1.2. Network Devices 


Under SOS, each peripheral device is controlled 
by software called a device driver. The 
SOS.DRIVER file on a SOS boot diskette must 
contain a driver for each physical device that 
you will be using (i.e., console, printer, up to 
4 floppy disks). Real floppy disks have SOS 
device names .D1 - .D4. 


. The PLAN 4000 system includes device driver 
software for various network devices. 
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Three network character devices exist: 


e NCMD for communication with the file 
server 

. NMSG for user station to user station 
communication 


.PRINTER for virtual printer support 
Eleven block structured devices exist: 
NI -.N11 ("virtual" devices) 


Virtual devices allow access to volumes that 
reside on a system disk connected to a (shared) 
file server station. 


In order for the user to have access to such 
devices, the related device driver software 
needs to be contained in the SOS.DRIVER file 
along with the device drivers for the physical 
devices being used. 


1.3 A Boot Diskette for Network Use , 


The PLAN 4000 system includes two boot 
diskettes, one with a Pascal interpreter, the 
other with a Business Basic interpreter. Obtain 
from your system manager a copy of one or both 
of these master network boot diskettes. 
(Henceforth, "boot diskette" will refer to your 
personal copy of one of the master network boot 
diskettes). 


The SOS.DRIVER file on the boot diskette 
contains the console driver (.CONSOLE) and the 
driver software to handle 3 network character 
devices (.NCMD, .NMSG and .PRINTER), as well as 
11 block structured network devices (.N1 - 
.N11). SOS.DRIVER is set up for 2 local drives 
and for the network interface card in slot 2. If 
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this meets your requirements, no reconfiguration 
is necessary. Simply boot the diskette. 


The Pascal boot diskette has been configured so 
that the shared library volume //LIB/APPLE3/SOS 
is | automatically mounted. (Network virtual 
volumes and naming conventions for them are 
discussed in Chapter 2 of the File Server User^s 
Manual. The shared library volume contains, in 
one location on a network hard disk, text, data, 
and codefiles for use by all network 
workstations). If you are using Business Basic,. 
you can use the NET program on the BASIC boot 
diskette to mount the shared library volume. 
(The NET program is discussed in Section 2.2. 
Concepts such as "mounting" virtual volumes are 
discussed in Chapter 5 of the File Server User^s 
Manual). | 


If you wish to add other device drivers, such as 
.SILENTYPE, .RS232 or .PROFILE, to the 
SOS.DRIVER file on your boot diskette, you can 
use the System Configuration Program (SCP) on 
the Apple /// System Utilities diskette to do 
so. If you wish to make a single code file 
containing ONLY the network drivers, use SCP to 
read into memory the  SOS.DRIVER file from your 
network boot diskette. Delete all other drivers 
(including  .CONSOLE) and generate a new system 
with a filename other than SOS.DRIVER (e-g., 
NETWORK DRIVER). 


The network driver software includes device 
drivers for 11 block devices, called virtual 
drives. Note that only the first five (.Nl - 
.N5) are active. The asterisk following some 
drivers indicates that they are inactive. 


You may use the "Edit Driver Parameters" section 
of the SCP to change the number of active 
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network virtual disks, to inactivate the network 
-PRINTER device, or to change its name. Note 
that if you want access to both a local printer 
and the network spooled printer, you must change 
the name of at least one of them. 


Note that in the Pascal environment, disks are 
searched in order, from the highest numbered 
unit to the lowest. If you wish to have standard 
system programs such as the Editor and Compiler 
found on local disks (the Profile, for example), 
the network drivers should appear BEFORE the 
local disks in the SCP driver list. You can 
change the order in the SCP driver list by 
changing the seguence in which driver files are 
read from the disk. If multiple copies are 
found, the one on the lowest is used. 


1.4 Booting Your Apple /// Workstation 


In order to use your Apple /// workstation with 
the network, you must have a network interface 
card inserted in your machine (System Physical 
Planning and Installation Manual, Chapter 3). 
You also need a boot diskette containing network 
device drivers. As discussed in Section 1.3 this 
is available from your system manager. 


When you boot a diskette whose SOS.DRIVER file 
contains the network drivers, you are connected 
to the network whose card is in the slot 
specified during system generation (SCP). 


If the network is unavailable when you -boot, the 
boot process will wait. If you wish to use your 
Apple /// without access to the network, press 
the <CTRL> and. «Open Apple? keys simultaneously 
and the network drivers will be disabled. If the 
network subsequently becomes available, you will 
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have to reboot to access the network drives. 


If you try to use a network interface card other 
than the Apple /// Network Interface Card, or if 
you are using an expired test version of the 
network drivers, the boot process will terminate 
with a System Error $01. 
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Chapter 2 


Using the Network 


2.0 Shared Disk Organization: Virtual Volume 
Names 


The PLAN 4000 system and SOS use similar disk 
organization and filenaming conventions. It is 
important to keep in mind from the outset the 
distinction between the two. 


Network users share mass storage by using 
portions of network shared disks called "virtual 
diskettes" or "virtual volumes". These virtual 
volumes are formatted for use in various 
operating systems. 


Network names refer to these shared network 
disks and to the shared virtual volumes in them 
(the "outsides" of virtual volumes). See Figure 
l. Network names are used when issuing network 
(or "file server") commands via the NET program 
(Section 2.2), to create, mount, rename, or 
otherwise manipulate whole virtual volumes. 
Conventions for assigning virtual volume names 
("pathnames") are discussed in detail in Chapter 
2 of the File Server User's Manual. 


SOS names refer to the nested directories and 
files within virtual volumes and within real, 
local diskettes and hard disks. You should give 
SOS names when using SOS facilities such as the 
F(iler or Editor to manipulate the contents of 
virtual or real diskettes (volumes). 


Note also that, as with the Apple // Pascal 
operating system, a SOS volume can be specified 
by its Pascal volume name (EXAMPLE: instead of 
/EXAMPLE). A SOS volume can also be specified by 
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Pascal unit number (e.g., #3:) if no nested 


subdirectories are involved. In the same way, 
the SOS device name for the volume can be used. 


Finally, virtual volumes are referenced using 
network drive numbers when network commands are 
being issued (e.g., UNMOUNT D3). The 
relationship between network drive numbers, SOS 
device numbers, and Pascal unit numbers is 
discussed in Section 2.5. 


2.1 Virtual Diskettes Of Variable Size 


Shared disk storage on the network is 
implemented by the use of "virtual volumes". 
You, as a network user, have the option of 
creating volumes that, at your workstation, 
appear to be real diskettes of variable size, 
formatted for use in the SOS Basic or Pascal 
environments. These volumes are in reality 
portions of your network’s shared disks. 


When virtual volumes are "mounted" on a 
"virtual drive" for use, they look like SOS 
minidiskettes (though not necessarily the same 
size as real diskettes). Their directories and 
files are arranged inside according to SOS 
pathnaming conventions. Virtual volumes are 
mounted using the NET program s MOUNT command. 
The NET program is discussed in Section 2.2. 


Apple /// users create virtual diskettes of type 
3. These SOS formatted diskettes can be used in 
the Apple /// Pascal, Business Basic, 
Visicalc ///, PFS ///, or other applications. 
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Figure 1 


File Server Disk /MAIN 


EN — UT . 
Subdirectories: USERS SOS 
Virtual Volumes: SMITH JONES LIB 
"d N rs "i Pd x 
i j | : l | 
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Subdirectories: f WORK IPLAY 
[ 
| 
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N / 
bu 7 
` P d 
w < > Pd 


'MAIN is a real Network Hard Disk. 


EXAMPLE is a virtual SOS Volume. 
SOS File /EXAMPLE/WORK/DOC.CODE is 
found in Network Volume . MAIN/USERS/SMITH. 
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Virtual disks can be any size from 10 to 32767 
blocks. They should be created as type “3”. 
Access and usage protection for virtual disks is 
described in Chapter 3 of the File Server User^s 
Manual. To create a virtual volume from the SOS 
environment, follow the procedure in Section 
2.3. The Apple /// Pascal user can also access 
Apple // type Pascal virtual disks. 


NOTE: SOS may impose additional constraints on 
the size (minimum and maximum) of its volumes 
(see Section 2.3). 


2.2 File Server Commands: The NET Program 


Virtual disks are created, "mounted", renamed, 
deleted, and otherwise manipulated using the 
network NET. program. 


Remember that SOS commands manipulate the 

files within your virtual volumes (which 

are themselves files on a shared hard 

disk), while network (file server) 

commands manipulate the volumes 
| themselves. 


This can be confusing, since the network 
commands are issued from within SOS (via 
the NET program), and since the network 
disk volumes and the files within them use 
similar naming conventions. 


The relationship between network drive 


numbers, SOS device numbers, and Pascal 
unit numbers is discussed in Section 2.5. 
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The NET program is an interactive Business Basic 
or Pascal program supplied by the network 
manufacturer, which allows a user to enter file 
server commands at the keyboard. In the Pascal 
environment, NET is generally made available as 
an executable file in the default library 
volume, which should be mounted at startup on 
device .N1 (drive 1) by a command in the 
Startemd file on your boot diskette (Section 
4.1). If NET is not found on the library volume, 
the system manager will know where it. is 
installed. | 


The NET program sends each command, as entered, 
to the file server (except for the local 
commands described below that are available in 
the Pascal NET program). The file server 
executes the command. If there is an error, a 
numeric error code and an error message will be 
displayed. A complete list of error messages is 
found in Appendix A. 


NET then redisplays on the user station screen 
its prompt (:) for another file server command 
to be entered. The cycle repeats until Q 
«Return» is entered; then control returns to the 
operating system command level. 


The following printout shows a sample Pascal 
session. User responses are shown in lower case 
to distinguish them from information displayed 
by Pascal and NET. (Actually, commands can be 
entered in either upper or lower case, and 
output from Pascal on an Apple /// is upper and 
lower case.) 
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COMMAND:E(DIT,R(UN,F(ILE,C(OMP,L(INK, X(ECUTE, 
x 

EXECUTE WHAT FILE? .nl/net 

ENTER NETWORK COMMAND 


: create lunch,t=3 
109,ROOT DIR NOT SPECIFIED; NO DEFAULT 


set dir /main/pascal 


[No message in response to a command indicates 
that the command was successfully executed.] 


show dir 
/MAIN/PASCAL 


:create lunch,t=3 


:q <return> 
COMMAND:E(DIT,R(UN,F(ILE,C(OMP,L(INK, X(ECUTE 


In this example, a user executes the NET 
program, which allows him (or her) to send 
commands to the file server. The user wishes to 
create a virtual volume for use on the network. 
This volume, a portion of one of the network^s 
shared hard disks, will be of type d. ig 
formatted to resemble a real SOS diskette (and 
since no size is given, by default the same size 
as a real diskette). 


. The user does not enter the volume’s full 
pathname, perhaps assuming that a part of the 
pathname will be added by a default, set at 
startup by a "SET DIR" command. 


No such default "partial" pathname has been set, 
however, and an error message is returned. The 
user then sets a default partial  pathname, 
/MAIN/PASCAL, for future convenience, and asks 
that it be displayed ("SHOW DIR"). The user then 
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creates the desired volume and quits the NET 
program. NET commands are discussed in detail in 
the File Server User^s Manual. 


2.3 Creating Virtual Diskettes 


Size is an optional parameter when CREATING a 


SOS virtual diskette. If no size is specified, 
each SOS virtual diskette is the size of a real 
minidisk, i.e., 280 blocks (each 2512 bytes 
long). 


Size may be specified with the CREATE command 
using the parameter: 


[, SIZE=Nb] 


where N is the number of 512 byte blocks. The 
maximum size is limited by the size of the disk 
unit on which the virtual diskette will be 
Stored and by limitations in the SOS operating 
system. Minimum size (256 blocks) is limited by 
SOS. The number of blocks for a SOS virtual. 
diskette must be: 


2256 (minimum) | 
| «22327067 (maximum for system disk) 
NOTE: The system also allows size to be 


specified in units of: 


C (characters-—-----1 byte each) 
S (sectors------256 bytes each) 
B (blocks------- 512 bytes each) 
blank (blocks------- 512 bytes each) 
Ko (kilo bytes--1024 bytes each) 


To create a 1000 block SOS disk and mount it on 
drive 1 (that is, on device .nl), do the 
following (drives are discussed in Section 
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2€9)1 
CREATE /MAIN/DOE/SOSDISK,T-3,SIZE-1000B,D2,UPD 


To have SOS initialize the directory of the 
volume, you must use the Apple /// Utility 
Program. Do this by X(ecuting /LIB/UTILS or 
.nl/UTILS from the Pascal command line; or, 
place the Apple /// Utilities diskette in your 
second disk drive and X(ecute 
.d2/SYSTEM.STARTUP. (including a "." after 
"STARTUP"). 


When the Utility menu comes up, select "Device 
handling  commmands". From the next menu, select 
"F" for Format. Enter the device number to be 
formatted (.nl in the example above) and the SOS 
pathname for the virtual volume. The Network 
volume 


/MAIN/DOE/SOSDISK 


might be named /SOSDISK, for example, or it 


could be named /DISKl. There is no need to use 
the same name as part of the network volume name 
and the SOS pathname, but such a strategy is 
often convenient. 


2.4 Using Virtual Diskettes In SOS 

Suppose that, as a brand new user, you want to 
write new Pascal programs or run existing ones 
on the network. What must you do to get 
started? 


In general, you (or the system manager) must: 


Boot an existing SOS diskette that gives you 
access to the NET program. 
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CREATE a SOS virtual disk. 


MOUNT it on the file server drive 2 or 3 for RW 


access (drive 1 contains the shared library 
volume). 


Format its directory using the Apple /// 
Utilities program, Device handling section, 


Format subsection (see Apple /// Owner^s Guide, 
p. 88). | 


If desired, add a NET command to your Pascal 
boot diskette Startcmd.Text (Section 4.1), to 
. nount the new volume at each startup. 


Use Utilities program (File handling section, 
Copy files subsection) to copy files from a real 
disk inserted in a minidisk attached to the user 
station, to the new virtual volume if desired. 
(See Apple /// Owner^s Guide, p. 73). 


Use the Editor, Compiler, and Linker to create, 
compile, and link Pascal programs, just as on a 
standalone Apple ///. 


For example, say that an educator has a set of 


arithmetic courses which he previously ran on a 
standalone Apple ///. Now he wants to present 
these same courses on the network. 


Let^s assume that he is authorized to allocate 
space on the shared disk /MAIN, in the directory 
COURSES. He wants to CREATE a virtual disk 
called  ARITHMETIC on it. He would give the 
CREATE command: 


CREATE /MAIN/COURSES/ARITHMETIC, T23,D2, RW 
(Assume that no protection of the new virtual 


volume is desired and that the size of a real 
diskette is satisfactory. CREATE is used here to 
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mount as well as create the virtual disk.) 


Then using the SOS Utilities program, he would 
format the directory on the virtual disk, and 
transfer files from the real disk to his virtual 
one. 


2.5 Using Virtual Drives 


In SOS, you can refer to your local hard disks 
and diskette drives, real and virtual, by their 
SOS device names or Pascal unit numbers. The 
correspondence of device name to unit number 
will vary according to how the SOS.DRIVER file 
on your boot diskette is configured. The display 
in Section 2.6.1 shows a typical configuration. 


When issuing network (file server) commands via 
the NET program, a "drive number", rather than a 
device name or unit number, must be specified. 
Devices .N1 through .Nll correspond to drives 
1-11. 


Drive n = SOS device .Nn 


If a volume is mounted on SOS device .N3, for 


example, it is referenced in a network command 
by "Dg" : 


UNMOUNT D3 


NOTE: When Pascal first comes up, it checks all 
units above number 128 and marks each one 
off-line if no type=3 (SOS formatted) virtual 
disk is mounted there. For this reason, disks 
mounted after the boot process can only be 
accessed and used by rebooting SOS (with no . 
“UNMOUNT ALL" command in your Startcmd.Text). 
Note that this is characteristic of the current 
(1.0) of Pascal and is subject to change by 
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Apple in subsequent releases. 


SOS will not unmount disks previously mounted, 
at power off or during the boot process 
following power on, unless explicitly ordered to 
do so with a NET UNMOUNT ALL command in your 
boot diskette Startcmd.Text, or issued from the 
NET program. Use of the UNMOUNT ALL command in 
Startcmd.Text prohibits access to virtual 
volumes mounted above unit 128. This results 
because, as described earlier, when SOS first 
boots, it checks drives for volumes. If a drive 
above Pascal unit 128 is empty, it is “written 
off" until the machine is rebooted. For this 
reason, volumes to be used on drives above unit 
128 must be mounted, after which the system must 
be rebooted so that SOS can discover the 
volumes. Using UNMOUNT ALL would defeat such a 
strategy. 


2.6 Local NET Commands 


In addition to the commands that it sends to the 
file server, the Pascal version of NET responds 
to a number of local commands that it executes 
itself. These commands are concerned with 
changing and displaying the drive status and 
network interface card slot number associated 
with each Pascal virtual drive (.Nl through 
.N11) and the file server command channel. 


2.6.1 SHOW DRIVES 
This command displays the status of all the 
Pascal units. The information displayed 


consists of the following: 


- the Pascal unit number. 
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SOS device name 


- unit type (real or virtual disk, message or 
command channel) 


- number of blocks on device (disks only). 
- "virtual channel" for network devices 
(i.e., the slot of the network card and 


station number of the file server.) 


—- network drive number 


In this example, the 


mounted on drive 3 (unit 12, device .N3). The 
file server station number is SFE. The SHOW 
DRIVES command does not list SOS or network 


user has a virtual 


names for mounted volumes. 


2912 


The SHOW DRIVES display has the following 
format: 
UNIT NAME TYPE BLK 
1] CONSOLE: 
2 CONSOLE: 
4 .D1  RDISK 280.B 
5 .D2 RDISK 280.8 
9 «PROFILE RDISK 9728.B 
10 .Nl VDISK SLOT=2, STN-SFE, Dl 
11 .N2 VDISK SLOT=2, STN-SFE, D2 
12 .N3 VDISK 560.B SLOT=2, STN=SFE, D3 
128 .NCMD VCMD SLOT=2, STN=SFE 
129 .NMSG VMSG SLOT=2, STN=SFE 
130 .N4 VDISK SLOT=2, STN=SFE, D4 
131 .N5 VDISK SLOT=2, STN=SFE, D5 
132 .N6 VDISK SLOT=2, STN=SFE, D6 
133 .N7 VDISK SLOT-2, STN=SFE, D7 
134 .N8 VDISK SLOT=2, STN=SFE, D8 
135 .N9 VDISK SLOT=2, STN-SFE, D9 


volume 
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2.6.2 SHOW FS 


This command displays the default “command 
channel” (consisting of a network card slot 
number and file server station number) to which 
file server commands are currently being sent 
using the .NCMD device. 


FS COMMAND CHANNEL IS: 
SLOT-2,STN-$FE 


2.6.3 SET .Nn[,.Nn,...] [, VIRTUAL] [, SLOT n] 


[,STN $nn] 


This command can be used to allow access to 
virtual volumes mounted at more than one file 
server, or more than one network. See Section 
2.8 for more details. 


If a drive is set VIRTUAL without specifying a 
slot or station, I/O will be directed to the 
same file server used by the command channel. 


2.6.4 SET FS[,SLOT n][,STN $nn] 
Sets the default "virtual command channel" for 


file server commands issued by NET or by 


subseguently run programs to the values 
specified. The initial default file server 


channel is the slot specified in SOS.DRIVER and 
station SFE. 


2.6.5 SPOOL TO/SPOOL OFF 


SPOOL TO device namelfile name 
SPOOL OFF 


where device name may be device name [.PRINTER 
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or PRINTER:] and file name may be ([.Dn/] 


filename or [.Nn/] filename (where n is a unit 
number, and filename is appended with the suffix 
.text, if it is not already specified and the 
last character is not a period). 


SPOOL TO specifies the device or file to which 
all responses will be routed. The redirection 
will continue until SPOOL OFF is issued. If the 
specified file already exists or is the same as 
the current spool file, the user will be 
prompted to overwrite it. To determine the 
current spool file, simply enter SPOOL TO 
without a destination. 


" When spooling to a file, the file will be 
properly closed after any one of the following: 


1. SPOOL OFF 

2. SPOOL TO some other file or device 

3. QUIT from NET. (Whatever has already 
been written will be saved.) 

4. WRITE ERROR 


2.6.6 | NOECHO 


Commands from a file (initiated by 
^filename) are usually displayed when they 
are executed; NOECHO suppresses this. 


2.7 Other NET Inputs and Commands 


In the pascal environment, the NET program also 
accepts the following inputs: 


; <anystring> Ignored as a comment. 
PRINT <anystring> Displays the text on the 


console. 
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command;command;... Multiple file server 
commands are allowed on 
the same input line if 
they are separated by a 
semi-colon. 


 *filename Causes commands to be read 


in from the Pascal text 
filename specified. 


2.8 Multiple File Servers And Multiple Networks 


PLAN 4000 systems may have more than one file 
server on the same network. Multiple file 
servers are accessible to user stations 
operating in the SOS environment. In addition, 
user stations may be attached to more than one 
network. 


A user station identifies file servers by the 
number of the slot containing the network 
interface card for the network that the file 
server is attached to, and by the station number 
of the file server on that network. 


User stations have two kinds of communications 
with file servers: users may issue commands to 
the file server, and may issue I/O requests for 
virtual volumes. A user station may be 
configured so that it has virtual volumes 
mounted on a number of different file servers at 
the same time. The SOS system can then be used 
to transparently access any combination of these 
virtual disks, just as if they were real disks, 
regardless of what actual file server station 
they are stored on. 


The commands SET DRIVES and SET FS discussed 
above allow the user to configure his or her SOS 
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drives so that virtual volumes can be accessed 
from multiple file servers and ` multiple 
networks. SET DRIVES allows the user to specify 
which slot (network) and file server each drive 
will refer to, and SET FS allows the user to 
mount volumes for the specified file server on 
those drives. | 


There are many interesting and complex system 
configurations that can be constructed using 
multiple file servers, but they are all built 
upon the same basic primitive operations. As an 
example, suppose that it is necessary to 
manually transfer a file within a SOS volume 
from one file server to another on the same 
network. 


Assume that, in addition to the primary file 
server on station SFE, the system manager has 
installed another file server on station S$FD. 
The following procedure will transfer a file 
called "XREF.TEXT" from the SOS volume with FS 
pathname volume  "/MAIN/USERS/SMITH/1" on the 
primary file server (SFE) to the SOS volume 
"/MAIN/ARCHIVE/PVOLS" on the second file server 
(SFD): 


l. Boot a Pascal volume. 


2. From the command level of the Pascal system, 
X(ecute the NET program. Issue the following 
commands: 


MOUNT /MAIN/USERS/SMITH/1,D2 
SET .N2 VIRTUAL 


(Mount the source volume at station SFE, 
drive 2. corresponds to SOS device .N2) 


SET FS STN SFD 


N 
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(Change default file server) 
SET .N3 STN $FD 

(Set destination drive ES STN $FD) 
MOUNT /MAIN/ ARCHIVE/PVOLS ,D3, UPD 
SET FS STN SFE 


(Restore the default file server for future 
commands) | 


You can use the SHOW DRIVES and SHOW FS commands 


to see the status of drives and the file server 
command channel. | 


QUIT 
(Exit from NET) 


3. Use "F" to go to the Pascal filer, and 
T(ransfer .N2/XREF.TEXT to .N3: 


.N2/XREF.TEXT, .N3/$ 


This example is "manual" in the sense that the 
commands are typed interactively. The same 
Operations can be performed from within a 
program by using the NETUNIT unit (Section 3.0) 
provided with the system to issue the commands, 
and then using Pascal I/O of any kind to 
transfer the data. Other interesting additions, 
such as using symbolic or indirect names instead 
of the file server station number? can be added 
at the same time. 
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2.9 Network Virtual Spooled Printer 


The network virtual  spooled printer is a 
character device that will accept text and write 
it to a file server volume. A print server can 
then print the text from this volume. Any 
number of stations can be generating such 
volumes simultaneously, and one or more print 
servers can be servicing the queues of volumes 
waiting to be printed. See the Print Server 
Installation and Operation Manual and Print 
Server Userľs Manual for more information about 
print servers. 


The virtual printer device is distributed with 
the device name .PRINTER, but can be changed 
when the drivers are configured, to avoid 
conflict with the same name used for a locally 
attached printer. 


Whatever the name, the virtual printer is used 
just like a local printer, by specifying the 
device name when you are asked for the name of 
an output device. For example, you can specify 
the virtual .PRINTER as the listing file for the 
Pascal compiler. Or, to get a listing of a text 
file, you can ask the F(iler to transfer the 
file to the virtual .PRINTER device. 


The virtual printer device accumulates 
characters in a character buffer which it 
writes, when full, to a volume it has created in 
the //SYSTEM/QUEUE/NEW directory on the file 
server. When the printer device is closed by 
SOS, the volume is unmounted and thus freed to 
be printed when a print server is available. 


(Opening and closing the printer device is 
generally performed automatically by the 
language interpreter and SOS, and usually will 
not be of concern. However, in the case of some 


2-18 4/1/83 


NETWORK 


low level I/O access, such as that by UNITWRITE 
in Pascal, the device may not be closed. In such 
cases, an explicit SOS CLOSE must be 
programmed). 


2.10 Running Programs In Protected Environments 


Applications programs which completely control 
their environment, such as VISICALC, may be used 
with the network virtual disk support provided 
that the required MOUNTS have been sent to the 
file server before the program is started. If 
necessary, this may be done by first booting a 
Pascal or Basic environment SOS disk and issuing 
the commands using NET, a STARTCMD file, or a 
Hello program, and then booting the application 
diskette. ! 


2.11 Capturing Apple /// Basic Files As ASCII 
Text Files 


In order to have the network print server print 
a Business Basic program you must save the BASIC 
program as an ASCII text file, then you must 
issue a print request for this text file. The 
process for saving tokenized BASIC programs as 
text files is the following: 


l. Load or type the BASIC program into memory. 

2. Type ^EXEC CAPTURE^, prepending CAPTURE with 
the proper pathname if it is not on your 
prefix volume. (e.g. “EXEC /LIB/CAPTURE if on 
the shared library volume). 


A few cautions: 


l. Do not “SAVE” your program after capturing 
it. The EXEC adds lines to your program. If 
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you must save it, type “DEL (^ before 
saving. 


You cannot capture line J. This is used by 
EXEC. If you have used this number, you MUST 


renumber your program if you want that line 
printed. 


The CAPTURE program is available from the 
shared SOS library volume 
(/MAIN/LIB/APPLE3/SOS). 
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Chapter 3 


Programming 


EN Using File Server Commands Within A Pascal 
Program 


NESTAR provides Pascal "units" that allow the 
Pascal | user to write programs that issue 
commands to the file server. The unit library 
distributed is called 


NETWORK.LIBRARY 
and it contains the following units: 


CMDUNIT - a Pascal regular unit that allows 
programs to issue file server or local 
commands (i.e., any command accepted 
by the NET utility program). In fact, 
this is the unit that the NET utility 
program uses. This unit requires the 
unit NETUNIT, also contained in 
NETWORK.LIBRARY. 


NETUNIT - a Pascal regular unit that allows 
programs to issue commands to the file 
server (local commands are NOT 
accepted here) and optionally gets 
responses back for processing by the 
program. In addition, NETUNIT contains 
routines that allow direct 
station-to-station communication. 


The contents of NETWORK.LIBRARY may be installed 
in  SYSTEM.LIBRARY at your local installation. 
If not, the Pascal program must use the $U 
option to specify the location of the unit 
library to the compiler. During linking, the 
same library name must also be given. 
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A program using CMDUNIT and/or NETUNIT must have 
the following "USES" in the source of the 
program: 


USES (*$U network-library-name*) NETUNIT,CMDUNIT; 


Note the order: NETUNIT must come before CMDUNIT 
for the declarations to compile without errors. 


If the program uses only NETUNIT, then "USES" in 
the source of the program can be simplified to: 


USES (*$U network-library-name*) NETUNIT; 


3.1.1 CMDUNIT 
If the user wants to execute file server or 
local commands (just as the NET utility program 
does), then the Pascal procedure CMD or  CMDLOOP 
in CMDUNIT should be used. 
The CMD procedure has the form: 

CMD (COMMAND, OPTIONS) 
where: 

COMMAND is a string variable whose value 
is the file server command or 
local command to be executed. 

OPTIONS is an integer variable which must 


be set to: 


O - don't echo command if error. 
l - do echo command if error. 
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Examples: 


CMD( “show mounts^,0); 
CMD(“show drives” ,0); 
CMD(^mount /MAIN/A,D1; MOUNT /MAIN/B,d2^,1); 


For programs in which the user enters file 
server or local commands from the keyboard until 
the user types QUIT or «escape», the  CMDLOOP 
procedure is provided. It has the form: 


CMDLOOP (PROMPT); 


where: 


PROMPT is the string variable whose value 


is the prompt to be issued to the 
user. 


Examples: 


CMDLOOP(^: ^); 
CMDLOOP(^FS command or QUIT: ^); 


The following program, COMMAND, demonstrates the 
use of CMDLOOP to execute file server commands. 
This is, in fact, the complete source listing of 
the NET utility program: ' 


PROGRAM COMMAND; 
USES (*SU /LIB/NETWORK.LIBRARY *),NETUNIT,CMDUNIT; 
BEGIN 


CMDLOOP(^: ^) 
END. 
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: e 1.2 NETUNIT 


To execute a file server command and get the 
return code back for evaluation by the program, 
use the NFSCMD procedure. The procedure has the 
form: 


RC := NFSCMD (NIL,COMMAND, RESPONSE); 
where: 


RC is an integer representing the 
"return code" sent back by the 
file server (see Appendix A for a 
list of return codes and their 
meanings). A return code of 0 
means no errors. 


NIL is a “virtual channel” pointer. 


Specify NIL for the default (and 
perhaps only) file server. 


COMMAND is a string variable whose value 


is the file server command to be 
executed. 


RESPONSE is a string "VAR" variable . whose 
value is set to the last response 
line sent back by the file 
server. If the command has been 
executed successfully, then the 
last response is usually "OK". 
Otherwise, the last response 
contains the error message text. 


All intermediate response lines are written to 
the screen. | 


NOTE: The NFSCMD procedure may wait an 


arbitrarily long time for the command to be 
executed and the wait may be inappropriate if 
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the program needs to check for other events 
frequently (such as key presses). For this 
reason, there is also a NFSCMDO procedure. The 
procedure has the form: 


RC := NFSCMDO (NIL,COMMAND,RESPONSE) ; 


which is identical to NFSCMD, except that the 
procedure will not retry if the network is not 
immediately available. The calling program 
should retry (and check for other events). For 
example: 


repeat RC :- NFSCMDO (NIL,COMMAND, RESPONSE); 
...check other events here... 


until RC <> 98; (*repeat until not network 
error (busy)*) 


From Pascal, the NET program automatically 
issues the control 84 code when necessary to 
inform SOS of disk changes. When the NFSCMD 
procedures are used from NETUNIT, to mount 
virtual volumes, IT IS THE USER'S RESPONSIBILITY 
TO USE THE  UNITSTATUS PROCEDURE OR ITS 
EQUIVALENT TO ISSUE THE NECESSARY CONTROL 84 OR 
CONTROL 85 OPERATIONS. 


To execute a file server command and get all the 
responses back for evaluation, (including those 
usually displayed on the screen without program 
intervention), use the NFSCMD1 procedure. The 
procedure has the form (to be typed on one 
line): 


RC := NFSCMD1 (NIL,COMMAND, RESPONSE , NEWCMDFLAG, 
| DONEFLAG); 


where: 
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RC is an integer representing the 
"return code" sent back by the file 
server. | 

NIL > is a "virtual channel" pointer. 


Specify NIL for the default (and 
perhaps only) file server. 


COMMAND | is a string variable whose value is 
p the file server command to be 
executed when NEWCMDFLAG is set to 
TRUE. When NEWCMDFLAG is set to 

false it is ignored. 


RESPONSE is a string "VAR" variable whose 
value is set to. the next (or first) 
response . line sent back by the file 
server. 


NEWCMDFLAG is a boolean variable whose value is 
TRUE when a command is initially 
sent to the file server. It is FALSE 
on successive calls which get the 
next response lines. 


DONEFLAG is a boolean “VAR” variable. Its 
initial value is ignored and it is 
set to TRUE if this is the last 
response line and FALSE if there are 
more response lines. 


For example, a program fragment might contain: 


CMD := “file server command’; 

RC := NFSCMD1 (NIL,CMD,RSP,TRUE,DONE); 
WHILE NOT DONE DO BEGIN 

RC := NFSCMDI(NIL,CMD,RSP,FALSE,DONE); 
END; l | 
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3.2 A Sample Program 


The following program, MININET, demonstrates the 
use of NFSCMD to send commands to the file 
server with a Pascal program. The MININET 
program will get an input line from the user and 
send it to the file server for execution. 


 MININET differs from NET in the following ways: 


1. Both the code number and reply returned by 
the file server are displayed on the 
console. | 


2. The commands referring to the user's own 
drives (SHOW DRIVES, SET FS SLOT, SET FS STN, 
SET .N1) are not available in MININET. They 
are executed by the NET program, using 
CMDUNIT, not by the file server. 


PROGRAM MININET; 
USES (*SU / LIB/NETWORK.LIBRARY *) NETUNIT; 


VAR 
RC: INTEGER; 
CMD,REPLY: STRING; 


BEGIN 
WRITELN (^Mini Command Program”); 
REPEAT | | 
WRITE (“FS COMMAND? ^); READLN (CMD); 
IF LENGTH (CMD) <> O THEN BEGIN 
RC := NFSCMD (NIL,CMD, REPLY); 
(* Send command to default file server *) 
WRITELN (RC,^,^,REPLY) 
END 
UNTIL LENGTH (CMD) » 0; 
| (*All done if nothing typed *) 
WRITELN (^Ciao.^) 
END. 
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A sample execution of the MININET program : 


Mini Command Program 
FS COMMAND? show date 
DATE IS 03/10/81 

FS COMMAND? foo 
1,ILLEGAL COMMAND 

FS COMMAND? ~~ 

Ciao. 


3.3 The SOS Basic Environment 


BASIC programs can send commands to the file 
server using PRINT and INPUT statements to a 
file which has been opened to device  ".NCMD". 
(Local commands, as described in sections 2.6 
and 2.7 for the SOS Pascal environment, are not 
supported in the Basic environment.) To open the 


file, use 
OPEN £1,".NCMD" 
and issue a command to the file server with 


PRINT #1;CMDS; 


(It is important to include the trailing 
semicolon so that a carriage return is not 
sent). 


File server responses must then be read using 


INPUT #1;RESULTS 
or network errors will result. 


The first character of the result is a blank if 
it is not the last response, and is a plus if it 
is the final message from the file server. All 
lines should be read until the response with a 
plus is received. 
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3.4 Apple // Compatibility 


The routines in NETWORK.LIBRARY have the same 
interface as routines supplied in the Apple // 
Network support. The only routine whose calling 
sequence has changed is FINDDRV, which now 
returns the "Dn" string to be used in file 
server commands as well as the integer volume 
number to be used as the first argument to 
UNITREAD and UNITWRITE. 


NOTE: any existing Apple // programs which use 
these units must be recompiled - not just 
relinked - with the Apple /// version of 
NETWORK. LIBRARY. | 


The Pascal BUSSEND and  BUSRCV procedure in the 
Apple /// NETUNIT unit are not limited to 
sending and receiving 256 bytes at a time, as 
they are on the Apple //. 


2 Reading a Station Number From Within a 
Program | 


It may be useful to read the station number (1 
to 255) from within a program. To obtain the 
station number, issue to the file server the 
command "SHOW STATION" and read ` the 
corresponding response, parsing it to obtain the 
station number. 


Using Pascal, follow the examples given in the 
previous sections, using one of the procedures 
in the NETUNIT unit to issue the command "SHOW 
STATION". The response string will have the 
form 


STATION IS $nn 
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By parsing this string, you can obtain the 
station number (in hexadecimal form). 


The station number can be obtained in decimal 
form from any Pascal program that uses the unit 
NETUNIT. When such a program is executed, part 
of the initialization process for the NETUNIT 
unit is the loading of the station address of 
each network interface card into an array called 
MYSTN (MYSTN: ARRAY [0..7] OF INTEGER). Thus, if 
the NIC in a user's station is in slot 6, the 
address of the NIC can be found in MYSTN [6]. 


A value of O in the MYSTN array for a particular 
slot indicates that the slot does not contain a 
network interface card. 


3.6 The Nestar CVAL Convention 


Apple /// Pascal allows one program to chain to 
another, and provides for a global string called 
CVAL to be passed as a parameter. 


See Page 41 of the Apple ///.Pascal Programmer”s 
Manual, volume 2 (Apple Product #A3L003) for a 
discussion of chaining programs in the Apple /// 
Pascal environment. To use these procedures in 
the FS environment with the  Nestar shared 
library, the line 


USES CHAINSTUFF; 


that immediately follows the Program heading 
must be replaced by 


USES (SU /LIB/SYSTEM.LIBRARY*) CHAINSTUFF; 


The Nestar definition of ‘the CVAL ‘variable 
allows it to be used both to specify a series of 
program to be executed, and to supply parameters 
to those programs. Programs which obey this 
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convention can thus be called as subroutines or 
be linked in a chain of consecutive program 
executions. Most  Nestar utility programs obey 
this CVAL convention. 


The general format of the CVAL string as a 
program begins execution is: 


parm//program2, parm2//program3 ... 


where "parm" is a parameter that is being passed 
to the current program. When it terminates, 
programl is the next program to be executed, and 
it is passed the string starting with  parm2. 


For example, if the CVAL string has the 
following value when program ABC is executed 


verbose//DEF ,nosend 


then program ABC will be executed with "verbose" 
as a parameter, after which program DEF will be 
executed with "nosend" as a parameter. 


Complex CHAIN sequences may be implemented by 
programs which add to as well as remove names 
from the CVAL string. Two procedures that 
manipulate the  CVAL string in accordance with 
this convention are shown here: 


GETPARM (parm-string); 
This procedure sets  "parm-string" to the parm 
provided to this program. In addition, if a 
CHAIN program name was given then a SETCHAIN is 
done (for this reason, GETPARM should be called 
even if the invoking program doesn't 
expect/accept a parm). This procedure should 
only be called once per program $ince multiple 
calls will unstack multiple  parm/program list 
entries. 


SETPARM (parm-string, program-name-string); 
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This procedure sets the parm for the next 
program which will be executed. In addition, the 
program name of the program to be executed after 
the next program has completed can be specified 
(e.g, the program name could be the original 
program name to cause a “return” to the original 
program when the next program has completed). 
SETPARM always returns and multiple SETPARM 
calls are legal (to set up a list of programs to 
execute). 
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PROCEDURE GETPARM (VAR PARM:STRING): 


VAR 
P: INTEGER; 
CVAL,PGM:STRING; 


BEGIN 
GETCVAL (CVAL); 
P :- POS (7//^,CVAL); 
(*find the end of our parm*) 
IF P = O THEN BEGIN 
PARM := CVAL; 
CVAL := ^^ 
END 
ELSE BEGIN 
PARM := COPY (CVAL,1,P-1); 
DELETE (CVAL,1,P+1); 
P := POS (^,^,CVAL); 
IF P = O THEN BEGIN 
PGM := CVAL; 
CVAL ss ^^ 
END . 
ELSE BEGIN 
PGM :- COPY (CVAL,1,P-1); 
DELETE (CVAL,1,P) 
END; 
IF PGM <> “” THEN SETCHAIN (PGM); 
(* XCTL pgm name *) 
END; 
SETCVAL (CVAL) 
END; 


PROCEDURE SETPARM (PARM,PGM:STRING); 


VAR 
CVAL: STRING; 


BEGIN 
GETCVAL (CVAL); 


SETCVAL (CONCAT (PARM,” //” ,PGM,” ,~ ,CVAL)) 
END; | 
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.7 The SOS Network Drivers: Advanced Device 
Information 


This section contains detailed information about 
the Apple /// network device drivers supplied by 
Nestar. General familiarity with SOS device 
drivers is assumed. This information is 
generally required for advanced programming 
applications only. 


All the network devices are contained within a 
Single device driver that can be configured for 
as many as 13 SOS devices. The device driver 
types are as follows: 


l. .NCMD is a character device through which 
commands are sent to a file server, and 
responses received. There can be at most one 
.NCMD device. The Pascal routines NFSCMD, 
NFSCMDO, and NFSCMD1 in NETUNIT are 
implemented using the .NCMD device. 


2. .NMSG is a character device which can be used 
to send and receive arbitrary blocks of data 
to or from another station. Although there 
can be at most one .NMSG device, any number 
of stations can be communicated to using it. 
The Pascal routines BUSSEND and BUSRCV in the 
NETUNIT unit are implemented using the .NMSG 
device. 


J. .PRINTER is an output only character device 
that can be used to create spooled files to. 
be printed by the print server. 


4. N1 through .N11 are block devices which 
represent virtual disks located on a 
fileserver. Although 11 such devices are 
assembled into the driver, only the first 5 
are active by default. The others may be made 
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active by the SCP program when a system is 
generated, but there are various limits on 
the number of such devices imposed by SOS and 
the langauge interpreters. All the network 
block devices are "formatter" devices and may 
be used by the SOS Utility program to format 
virtual disks. 


3.8 Device Configuration Block 


All SOS devices are allowed to have a Device 
Configuration Block (DCB) that contains device 
dependent control and status information. The 
information in the DCB can be examined and 
modified by device calls described later. All 
the network devices have identical DCBs, whose 
format is as follows: 
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Offset Name Length Default Description 
00 MODE 1 1 1 for NMSG Network connect 


O for others persistence mode 
O=try forever, 
l=try briefly 


01 MODE2 l 0 Speaker click 


control Osclick, 
=no click 


02 MODE3 1 0 (Currently 
unused ) 


03 SLOT 1 2 Slot number of 
network card 


04 STATION 1 SFE Station number 
to connect to 


05 PORT 2 0 Port within 
STATION 
(currently 
unused ) 


07 PASNUM 1 n For block 
devices: 
Virtual drive # 


07 MTYPE if For .NMSG: 
Message type 


08 NWERR 1 Detailed 
network error 
code 


ho 
O 


09 BLKLEN For block 
devices: 
virtual 


disk size 
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The MODE] flag controls whether the network 
drivers should wait forever to establish the 
initial connection to a remote station. For 
communicating with server stations it is usually 
set to “wait forever" mode, but for 
communicating with non-servers that may not be 
responsive for relatively long periods, it is 
best to set MODEl to 1 to avoid excessive bus 
overhead. It is this flag that is used to effect 
the difference between NFSCMDO and NFSCMD in 
NETUNIT. 


The three fields SLOT, STATION, and PORT 
constitute the identification of a remote. 
process called a CHANNEL in the NETUNIT 
documentation and interface. 


The PASNUM field contains the virtual drive 
number which is sent to a fileserver when an 1/0 
operation is requested. This number corresponds 
to the "Dn" parameter on the CREATE and MOUNT 
command. The virtual drive number initially 
corresponds to the SOS name of the device: .N1l 


is virtual drive 1, .N2 is virtual drive 2, and 
SO on. 


The MTYPE field is used, for the .NMSG driver, 
to communicate the type field of the message 
sent or received. 


The NWERR field describes the last 


device-dependent error code returned to SOS, as 
follows: 
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Code Code Meaning 
(hex) (decimal) 


$30 48 Checksum failure (more than 15 
retries) 

$31 49 This station is not addressed. 

$32 50 User abort (CTRL-OpenApple) 

$33 51 Station address error 

$34 52 Timeout 

$35 53 Collision 

$36 54 Length error (received packet 
too big) 

$37 55 Packet sequence error from 
fileserver 

$38 56 Network busy 

$39 57 Incoming message is arriving 

$ 3A 58 No longer connected 

$ 3B 39 Already connected ` 

$3C 60 Can^t open virtual print volume 


3.9 Device Driver Calis 


The network device drivers support all the 
primitive I/O operations as defined by SOS, 
including, as appropriate for the device type, 
D-INIT, D-READ, D-WRITE, D-STAT, D-CNTL, D-OPEN, 
and D-CLOSE. 


The read and write calls are normally done 
through a language interpreter. In Pascal, 
UNITREAD and UNITWRITE are used (directly or 
indirectly), and in Basic  INPUT and OUTPUT are 
used. | 


The status and control calls accept a code and 
data area, and may be called directly from 
Pascal using the UNITSTATUS procedure. See 
pages 211-213 of the Apple  /// Pascal 
Programmers Manual Volume 1 for details of 
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UNITSTATUS. 


3.10 The .NMSG Device Driver Calls 


The .NMSG driver sends or receives an arbitrary 
block of data to or from another station. Each 
write operation may result in multiple packets 
being transmitted as necessary. The receiving 
station must be. executing a read operation on 
the .NMSG device to receive the message. If the 
receiving station attempts a write operation to 
-NMSG when a message is arriving, error 57 
("incoming packet is arriving") is returned, and 
the station should then do a read operation. 


The CHANNEL area of the DCB is used to identify 
the station being communicated with. It should 
be set before a write operation and examined 
after a read operation. 


The control and status calls for .NMSG are the 
same as for .NCMD, with the following additions 
for setting and examining the message length and 
type: 


Status Meaning 


code : 
83 Return message type byte in data area 
84 Return message length (two bytes) in 


data area 


Control Meaning 

code 

83 Specify the message type byte for the 
next outgoing message. (The message 
length is specified by the length of the 
data in the write operation.) 
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3.11 The .Nl ... .Nll Device Driver Calls 


The network block devices respond to SOS block 
calls just like local block devices. The file 
server is indicated by the current CHANNEL in 
the DCB of the device, and is sent the virtual 
device number from the DCB as the identification 
of the virtual disk being read or written. The 
status and control calls are as follows: 


Status Meaning 


code 

00 Return the block device status byte. 
(Always O0 for network block devices.) 

01 Return the DCB (as for .NCMD). 

81 Same as Ol. 

82 Return the CHANNEL from the DCB. 

83 Return the virtual drive number from the 
DCB. | 

85 Return the station address for this 


network card of this station. 


Control Meaning 


code 

00 Reset the network interface card 
hardware, and set MODEL and MODE2 to 
zero. 

01 Store the DCB (as for .NCMD). 

81 Store the DCB (as for .NCMD). 

82 Store the CHANNEL (as for .NCMD) 

83 Set the virtual drive number in the 
DCB . | - 


/ 
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84 © Set the disk change flag, read the 
descriptor of the virtual disk, and set 
MAXBLOCKS to tell SOS how big the disk 
is. 


85 Set the disk change flag. 


IMPORTANT NOTE: SOS must be informed whenever a 
virtual disk has been changed by a MOUNT or 
CREATE command, because certain directory and 
bitmap information is kept stored within SOS and 
would be incorrectly applied to the new disk. 
This is analogous to hardware for ‘the local 
floppy disk which signals that the diskette has 
been changed. 


Control operations with code 84 or 85 are used 
to inform the driver that it, in turn, is to 
inform SOS (using the “media changed" error 46) 
that the virtual disk has been changed. In 
addition, control code 84 causes the descriptor 
of the virtual disk to be read, and the 
MAXBLOCKS field of the SOS DIB to be updated so 
that SOS knows the new size of the block device. 
This is necessary so that a format operation 
will correctly initialize the directory 
structure. 


From Pascal, the NET program automatically 
issues the control 84 code when necessary to 
inform SOS of disk changes. When the  NFSCMD 
procedures are used from NETUNIT, to mount 
virtual volumes, IT IS THE USER^S RESPONSIBILITY 
TO USE THE UNITSTATUS PROCEDURE OR ITS 
EQUIVALENT TO ISSUE THE NECESSARY CONTROL 84 OR 
CONTROL 85 OPERATIONS. 


Note that there are several problems with the. 
way that the Apple Pascal system handles the 
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"media changed" error returned by your block 
device drivers. Specifically, 


1. Under some conditions, UNITREAD and UNITWRITE 
may return the "media changed" error. If so, 
the operation should be retried. The media 
changed error is IORESULT 46, not documented 
in A3L0003 version of the Pascal Programmers 
manual. 


2. The Pascal system does not use the media 
changed error to invalidate its stored copy 
of an Apple II format directory. Errors that 
operations such as RESET may use the old 
directory even after a new disk has been 

"mounted and disk change signalled. 


3.12 Device Identification Codes 
The manufacturer ID assigned to Nestar by Apple 


is $0022. The devices types and FPB. of the 
various drivers are as follows: 


DEVICE TYPE SUBTYPE 
.NCMD | $65 $01 
.NMSG  $65 $02 
.PRINTER $41 $04 


.N1l...N11 $F2 $01 
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Chapter 4 


Additional Utilities 


4.0 Network Utility Programs 


Additional network utility programs available to 
the Apple /// user are: 


STARTUP (Section 4.1) 

TREEWALK (Section 4.2) 
Run the programs by  X(ecuting)  /LIB/PROGRAM 
where "LIB" is the shared library volume on your 


network that contains the desired utility 
t PROGRAM" : 
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4.1 STARTUP Command Program 


STARTUP is the program that runs automatically 
in the user station when the boot volume is 
mounted. STARTUP is called NESTAR.START on the 
shared SOS library volume /MAIN/LIB/APPLE3/SOS. 
It is the program that is SYSTEM.STARTUP on the 
APPLE /// boot diskette supplied by Nestar. 


STARTUP is called NESTAR.START on the shared SOS 
library volume /MAIN/LIB/APPLE3/SOS. It is the 
program that is SYSTEM.STARTUP on the APPLE /// 
boot diskette supplied by Nestar. 


STARTUP first checks the booted disk for a file 
named SYSTEM.STARTUP. If present, it is chained 
to. Otherwise, STARTUP reads a file from the 
booted disk called STARTCMD.TEXT and interprets 
each line as a command. 


The STARTUP program reads a file from the booted 
disk called STARTCMD.TEXT and interprets each 
line as a command. The format of each command 
is: 


<command> ::= <verb><blanks> <optional-operand> 


The legal «verb? <operand> sequences are as 
follows: | 


; Kanystring? Ignored as a comment. 
PRINT<anystring> Print the string on the 
| Screen. 


CLEAR Clears the screen. 
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NET<fileserver command>Executes file server or. 


NOECHO <command> 


ASK <command> 


local command (e.g., MOUNT 
or SET DRIVE). 


Executes <command> but 
doesn't print it. 


Asks whether to execute 


<command>. 


ASK=Y <command> 


ASK=N <command> 


ASK ... PROMPT text 


CONTINUE 


Same as ASK, except that a 
carriage-return (only) 
response means yes. 


Same as ASK, except that a 
carriage return (only) 
response means no. 


The PROMPT option on ASK 
allows you to use your own 
prompt text. The prompt is 
NOT quoted and consists of 
whatever follows the word 
"PROMPT". 


Asks if it is ok to 
continue. A reply of no 


means QUIT. 


CONTINUE-Y 


Same as CONTINUE, except 


. that a carriage return 
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(only) response means yes. 
The prompt on screen will be 


START 


CONTINUE=N 


SET USER id 


SHOW FORMDATE 


NEWS 


CHAIN<program name> 


CONTINUE (Y/N)? 


and any typed response will 
replace the default Y. 


Same as CONTINUE, except 
that a carriage return 
(only) response means no. 


Sets a file server lock with 
the id specified. The 
convention is that "id" are 
your initials and the lock 
name generated is  USER.id. 
This allows a user to issue 
the file server command 
"SHOW ALL LOCKS" to 
determine the initials of 
the users currently using 
the network. 


Displays the date and time 
on the screen. The format 
is: 

Day dd-Mon-Year hh:mm:ss 


Displays general system 
information (contents of 
/LIB/NEWS. TEXT). 

Passes control to the 


program named. Note that 
control is never returned to 
the startup program SO 
commands following this 
command are not processed. 
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SET DATE Sets the system date to the 
current date (from the file 
server), as if the user had 
used the D(ate command in 
the Pascal Filer. 


QUIT | Exits the STARTUP program. 


Example 


; this is abcl:startcmd.text 

PRINT . 

PRINT THIS IS /MAIN/USERS/ABC/1 
PRINT 

cont inue=y 

set date 

noecho set user abc 

net SET DIR /MAIN/USERS, PRVPW=xxx 
net MOUNT ABC/TEMP,D1,RW,SHR 

PRINT 

ask=n news prompt display current news 


This list of program commands begins with a 
comment ignored by the startup program ("this is 
startcmd.text"). When the volume is booted, 
"THIS IS /MAIN/USERS/ABC/1” is printed on the 
user-station screen. The user is then asked 
whether the startup program should continue or 
not. Typing "n" «return? quits the program and 
the Pascal command line comes up. Typing 
(return? causes the startup to continue. The 
program then sets the Pascal system date to the 
current file server date. 


A user id is then set in the system. A default 
partial pathname is set, as well as a private 
password that may be required to access 
directories or virtual volumes. 
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The virtual volume /MAIN/USERS/ABC/TEMP is 
mounted on drive dl  (.nl), for shared, 
read/write use. 


Finally, the user is prompted to display the 


system s news. Pressing <return>, however, is 
equivalent here to "no". 
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4.2 TREEWALK Utility Program 


TREEWALK allows you to apply NET program network 
commands to more than one virtual volume and/or 
directory at a time. 


When you specify a command and directory, 
TREEWALK will apply that command to the 
directory, to all volumes and directories listed 
in that directory, and to all volumes and 
subdirectories beneath that directory. 

To use TREEWALK, X(ecute from the Pascal command 
line /LIB/TREEWALK. 


Command Syntax: 


command [pathname] [options] 


Legal commands are: 


LIST PROTECT 

DELETE QCuit 

FS RENAME 

HELP SHOW PROTECTION 


? 


TREEWALK commands, for the most part, are 
extensions of file server commands simply 
applied to the entire subtree of the specified 
path, instead of the single path. Type an «esc? 
to abort a TREEWALK command. 


For a more detailed description of a command, 
type: “HELP command". 
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LIST [pathname] 


This command gives a nested listing of the 


specified pathname. The parhnene s is a legal file 
server pathname. | 


SHOW PROTECTION [pathname] 


Issues a file server SHOW PROTECTION command for 
each directory or file found by traversing the 
specified path. If you only wish to traverse a 
specific subtree, answer "Y" to the "Show [path 
name of subtree]" and answer "N" to the subtrees 
you don't wish to see. 


PROTECT [pathname] [,protection list] 


Protects each file found by traversing the 
specified path, with the protection list. If you 
wish to traverse a specific subtree answer "Y" 
to the "Protect [path name of subtree]" prompt 
and answer "N" to the subtrees you don’t wish to 
see. You may optionally be prompted before 
protecting each directory or file by responding 
"Y" to the "Prompt for each directory or file" 
prompt. 


DELETE [pathname] 


This command issues a FS DELETE command for each 
directory or file found by traversing the 
specified path. If you wish to traverse a 
specified  subtree, respond "Y" to the prompt 
"Delete [subtree]?", or “N” if you don"^t wish 
to traverse that subtree. You may optionally be 
prompted before deleting each directory or file 
by responding "Y" to the "Prompt for each 
directory or file" prompt. 
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RENAME [pathname] 


This command issues a FS RENAME command for each 
directory or file found by traversing the 
specified path. If you wish to traverse a 
specified  subtree, respond "Y" to the prompt 
"Rename [subtree]?", or “N” if you don"^t wish 
to traverse that subtree. If you wish to rename 
a directory or file, type in the new name after 
the prompt: | 


-->RENAME SUBTREE, 
If you don’t want to rename that path then just 


enter a <cr>. 


FS 


* 


This command allows you to enter file server 
commands from TREEWALK. 


Entering 
FS command 
causes one file server command to be issued. 
Entering 
FS «return» 
causes the NET prompt to be displayed. File 


server commands can be entered one at a time 
until "Q" «return? is entered. 
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Appendix A 


Error and Information Messages 


When the file server receives a file server 
command from a user station, it executes the 
command, if possible, and, in any case, returns 
two variables: | 

- return code-an integer between 0 and 140 


- return message, such as OK, ILLEGAL COMMAND, 
or TYPE-Apple /// PASCAL 


Messages are of several types: 

- information, such as OK, IN USE, TYPESBINARY 

- user errors such as syntax errors or 
attempting to access a Network file without 


the necessary access rights 


- System errors such as memory full or disk 
full; these should be reported to the system 
manager. 


In this list, messages are classified as: 
general syntax 
pertaining to a specific command 
System errors 
file system errors. 


Some Pascal I/O error messages may be returned 
as a result of network operations: 
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16 Write-protect error: the specified 
diskette is write-protected. 


64 Device error: failed to complete a read 
or write correctly. 


Error 16 occurs when you attempt to write into a 
virtual volume that has not been mounted with 
READ/WRITE access. 


Error 64 occurs when, for example, when the 
system attempts to read or write past the end of 
the volume. This might occur if a block number 
is given that is outside the range of the file, 
or if you initialize a virtual volume to a size 
larger than that given when you created it. 


Error 64 may also occur if the network hard disk 
has been damaged. | 
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General Syntax (0-19) 
0,0K 


(Not an error.) The command was  syntactically 
correct and was executed without error. 


1, ILLEGAL COMMAND 


The command verb cannot be recognized, or cannot 
be executed from this user station operating 
system environment. The command verb is the 
first word of the command, and must be separated 
from the rest of the command with one or more 
blanks. 


2,NAME PARAMETER REQUIRED 


The first parameter of the command must be a 
non-null pathname. 


3, UNRECOGNIZED PARAMETER 


A keyword parameter was not recognized. Check | 


the spelling carefully, and make sure that it is 
properly separated from the previous and 
following items with commas. 


4, ILLEGAL DRIVE NUMBER 

A drive number must be specified with "D" 
followed by an integer in the range 1 to ll. 
Example: "D4". 

5,ILLEGAL STATION NUMBER 


A station number must be specified as a 


two-digit hexadecimal number preceeded with $, 
in the range $1 to $FE. Example:  "S2D". 
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7,PARAMETER APPEARS TWICE 


À keyword parameter appears more than once in a 
single command. There can only be one occurence 
of a keyword parameter, even if multiple 
occurences have the same value. 


8, ILLEGAL TYPE PARAMETER 


The "T=" value is not one of the legal volume 
types. It must be one of B (binary), D (Apple 
// DOS), P (Apple // Pascal), Y (directory), S 
(system). C(Apple // CP/M), 3(Apple /// SOS), 
I(IBM PC DOS), U(IBM PC p-SYSTEM PASCAL) 
T(text). Example: "TzP". 


9, COMMAND TOO LONG 


A file server command must be no longer than 80 
characters. In unusual cases where this is a 
problem, long commands can often be shortened by 
using a default directory, or by assigning 
access rights in a subsequent PROTECT command. 


10,PARAMETER TOO LONG 


The new name given as the second parameter of 
the RENAME command must be no more than 15 
characters long. Remember that RENAME changes 
only the last name in the sequence of names 
which constitute a  pathname. If you wish to 
change the name of a directory, give the 
pathname of the directory itself as the first 
parameter of RENAME. 


11,ILLEGAL PROTECTION PARAMETER 


The value of the PUBACC, GRPACC, or PRVACC 
protection item is incorrect. The value must be 
some combination of the letters RWECD (read, 
write, erase, create, and delete), or may be 
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null. For example, “GRPACC=RW" or "PUBACC-". 


12,NO STATION CMD; USE SNN PREFIX 


The "station" command has been removed. Use 
“Snn <command>" where on is the station number 
on whose behalf you wish to issue the command. 
(file server console only.) 


13,ILLEGAL NUMBER (NEGATIVE OR TOO BIG) 


The number was less than 0 or bigger than 
32767. Number may be specified in decimal, or 
in hexadecimal preceeded by $. Examples: "42", 
"SlA3". : 


19,HELP FILE NOT FOUND 


There is no HELP file for the word used as an 
operand of the HELP command. Use the HELP 
command with any parameters to see what the 
possible HELP parameters are. (The system 
manager has the option of removing all HELP 
files to save space.) 


Create (20-25) 


20,TYPE PARAMETER REQUIRED (T=) 


The type parameter was missing. Example: 
"Ten " 


21,SIZE OUT OF RANGE (OB OR »32752B) 


The value of the SIZE parameter was negative or 
greater than 32752 blocks. Each block is 512 
bytes. Other units that can be specified are C 
(characters), S (256-byte sectors), and K (1024 
bytes). If the units are omitted, B (512-byte 
blocks) is assumed. Examples: “SIZE=2 80", 
| “SIZE=2000S”". 
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23,SIZE PARAMETER REQUIRED WITH T=B 


Ihe SIZE parameter must be specified to create a 


binary volume. The size may be an overestimate 
of the size of the data to be BSAVEd into the 
volume, but it must not be less. 


24,SIZE OUT OF RANGE («1C OR >48K) 


The limits on the size of a binary (T-B) file 


are between 1C (one byte) and 48K (49152 bytes) 
regardless of the units used in the 
specification. 


Delete (25-29) 
29,CURRENTLY MOUNTED OR DEFAULT DIR 


You cannot delete a volume which is currently 
mounted by any station, or which is the default 
directory (see the SET DIR command) of any 
station. | 


Mount (30-34) 
30,DRIVE REQUIRED 


You must specify what drive the volume is to be 
mounted on. Example: "dl". 


31,IN USE 

The volume you asked to mount is in use by 
another station. You are therefore denied 
exclusive use of that volume. 

32,IN EXC USE 

The volume you asked to mount is in exclusive 


use by another station. You are therefore 
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denied any use of the volume. 
34,RW NOT ALLOWED ON DIRECTORIES 


You are not allowed to mount a directory (T=Y) 
volume for write access. 


Unmount (35-39) 
35,DRIVE OR "ALL" REQUIRED 


You must specify a drive number or "ALL" on the 
UNMOUNT command. Examples: "UNMOUNT D1", 
"UNMOUNT ALL". 


36,NOT CURRENTLY MOUNTED 


The drive number specified in the UNMOUNT 
command does not have any virtual volume mounted 
on it by the file server. 


Lock (40-44) 

40,ILLEGAL LOCK NAME 

A lock name must be 1 to 15 characters long. 
41,IN USE 


The lock name specified is in use by another 
station. You are therefore denied exclusive use 
of the lock. 


42,IN EXC USE 
The lock name specified is in exclusive use by 


another station. You are therefore denied any 
use of the lock. 


Unlock (45-49) 
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45, NOT HELD 


The lock name specified is not currently held by 
your station. 


BSAVE, BRUN, BLOAD (50-55). 
50,COMMAND NOT ALLOWED FROM THIS STATION 


The BSAVE/BLOAD/BRUN commands may only be 
executed from an Apple // user station. 


51,NOT BINARY 


Ihe pathname indentifies a volume which is not 
binary (T=B). Only binary volumes can be used 
for BSAVE, BLOAD, or BRUN commands. 


52,NOT PREVIOUSLY SAVED 


The binary volume was created but has never had 
any data written into it using the  BSAVE 


command. It can not not be used with BLOAD or 
BRUN until it has been BSAVEd into. 


53,FROM PARAMETER REQUIRED 


For BSAVE, the FROM parameter, which specifies 
the memory area from which data is to be taken, 
must be provided. Example:  "FROM-$1000". 


54,SIZE PARAMETER REQUIRED 


For BSAVE, you must provide the SIZE parameter 
on the BSAVE command to indicate how much data 
is to be saved. This value must be less than or 
equal to the size of the volume specified on the 
original CREATE command. Example: 
"SIZE-256.C". 
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55,FILE WAS THERE; REP NOT SPECIFIED 


Data has already been saved in the binary 
volume. To replace that data, you must specify 
"REPLACE" as a parameter in the BSAVE command. 


Set/List (56-58) 
57,FILE IS NOT A DIRECTORY 


The pathname given in a SET DIR command 
identifies a volume which is not a directory 
(TY). 


538 ERROR IN SET TIME PARAMETERS 

If the date parameter was supplied, it was 
incomplete or contained invalid fields. If the 
time of day parameter was supplied, it contained 
invalid fields. 

Show (59-69) 

59, TYPE=SYSTEM 

(Not an error.) The volume mounted on the drive 
for which you did a "SHOW TYPE" is a system 
volume (T=S). 

60,SHOW OPTION NOT RECOGNIZED 

The operand of a "SHOW" command was not 
recognized. Check the spelling and make sure 


there are no extraneous items in the command. 


61,DRIVE REQUIRED 
For the "SHOW TYPE" command you must specify the 


drive number on which the volume is mounted. 
Example: “SHOW TYPE D12". 
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62,NOT CURRENTLY MOUNTED 


The drive number specified has no volume mounted 
on it by the file server. _ 


63,TYPE=APPLE // CP/M 


(not an error.) The volume mounted on the drive 
for which you did a "SHOW TYPE" is an APPLE // 
CP/M volume. (T=C). 


64,NO DEFAULT DIRECTORY SET 


(Not necessarily an error.) This response to the 
"SHOW DIR" command indicates that there is no 
default. directory established for this station 
by the file server. 


65,TYPE-APPLE // PASCAL 


(Not an error.) The volume mounted on the drive 
for which you did a "SHOW TYPE" is an Apple // 
Pascal volume (T=P). | 


66,TYPE=APPLE // DOS 


(Not an error.) The volume mounted on the drive 
for which you did a "SHOW TYPE" is an Apple // 
DOS volume (T=D). 


67 , TYPE=BINARY 


(Not an error.) The volume mounted on the drive 
. for which you did a "SHOW TYPE" is a binary 
volume (T-B). 


68, TYPE=DIRECTORY 
(Not an error.) The volume mounted on the drive 


for which you did a "SHOW TYPE" is a directory 
(T=Y). . 
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69,UNKNOWN TYPE 


The volume mounted on the drive for.which you 
did a "SHOW TYPE" is not a standard volume 
type. 


70, yymmddhhmms sw 


(Not an error) Returns date and time information 

in encoded form. For example, the FS command 

TIMESTAMP returns the current year, month, day, 

hour, minute, second, and day of the week in the 

form 70,8104301859381 (that is, 6:59 P.M., 
Sunday, April 30, 1981). 


71,--t--tt--t-t---- 


(Not an error) Returns types of virtual disks 
currently mounted on drives 1-16 
(Y,P,D,B,C,3,1,U,T). The system responds to the 
FS command SHOW TYPES using this format. 
72,TODAY IS DD-MON-YYYY HH:MM:SS 


(Not an error.) This is the response to the SHOW 
TIME command. 


73,TYPE-TEXT 


(Not an error.) The volume mounted on the drive 


for which you did the SHOW TYPE is a text volume 
(T=T). 


74,TYPE=Apple /// SOS 
(Not an error.) The volume mounted on the drive 


for which you did the SHOW TYPE is an Apple /// 
SOS volume (T=3). 
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75,TYPE=IBM PC DOS 


(Not an error.) The volume mounted on the drive 
for which you did the SHOW TYPE is an IBM PC DOS 
volume (T-2I). 


76,TYPE=IBM PC P-SYSTEM PASCAL (Not an error.) 
The volume mounted on the drive for which you 
did a "SHOW TYPE" is an IBM PC p-System Pascal 
volume (T=U). 

Local Commands (90-92) 

90,DRIVE(S) REQUIRED 


A drive number is required for this command. 
Example: "SET .N1 VIRTUAL". 


91,DRIVE NUMBER CAN NOT BE USED 

There are 12 drives (also called "volumes") in 
Apple Pascal, but only some of them can be made 
virtual with the SET DRIVE local command. 

92,NO SOS NETWORK DRIVER 


Returned when a local command includes an 
inactive or nonexistent device. 


System Errors (94-99) 
94,NOT CONNECTED 


This is a network error that indicates that the 
connection to another station has been 
terminated prematurely. 


95,UNRECOGNIZABLE NETWORK RESPONSE 
The last response message from file server did 


not contain a numeric error code, as expected. 
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This may indicate incorrect logic in the use of 
NETUNIT procedures from within Pascal programs. 


96,NO NETWORK CARD IN SLOT 


The slot number specified does not have a Nestar 
network interface card installed, or the card ís 
defective. 


98,NETWORK ERROR 


The network routines were unable to complete the 
transaction. The error may be transient; see 
the description of NETUNIT for more 
information. This error does not occur from 
most user level programs, such as NET. 


99 ,USER ABORT 


The network abort key <CONTROL><open-apple> was 
pressed while a network transaction was queued 
up or in progress. The transaction was 
aborted. 


File System Errors (100-140) 


101,END OF FILE OR RECORD OUT OF RANGE 


An attempt was made to read a block or sector of 
a volume which is outside the legal range for 
that volume. 


102,FILE NOT FOUND 


The volume specified by the pathname was not 
found, or one of the directories in the pathname 
was not found. Check the spelling of each 
filename in the pathname. If the name does not 
begin with a slash, check that the current 
default directory is the correct one. 
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103,BAD DELIMITER IN PATHNAME 


A delimiter other than "/" or ":" was found in a 
pathname. Make sure that you have not omitted a 
comma separating the pathname from other 
operands in the command. 


104,FILE NAME OR PASSWORD TOO BIG 


A single filename (the part between slashes in a 
Pathname), or password (the part after a colon 
in a pathname) is longer than the maximum of 15 
characters. 


105,NO ACCESS FOR READ TO DIRECTORY 


You have been denied read access to a directory 
which is part of the specified pathname. 


106,NON DIRECTORY FOUND IN PATHNAME 


One of the names in the pathname (other than the 
last name) identifies a volume which is not a 
directory (T=Y). Only the last thing in a 
pathname can be other than a directory. 


107,END OF PATHNAME IS A DIRECTORY 


The pathname specifies a directory (T=Y) in a 
context where a  non-directory volume is 
required. 


109,ROOT DIR NOT SPECIFIED; NO DEFAULT 


The specified pathname does not begin with a 
slash, and there is no default directory 
recorded for this station by the file server. 
If you wish to completely specify the  pathname, 
begin with a slash and the name or number of the 
disk unit. If you wish to use the current 
default directory, do not begin the pathname 
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with a slash. You may use the "SHOW DIR" 
command to find out the current default 
' directory, and the "SET DIR" command to 
establish one. 


110,NO ACCESS FOR READ 


You have been denied read access to the volume 
specified by the pathname, or to a directory 
along the path. 


111,NO ACCESS FOR WRITE 


You have been denied write access to the volume 
specified by the pathname. 


112,NO ACCESS FOR APPEND (not yet implemented) 


You have been denied append access to the volume 
specified by the pathname. | 


113,NO ACCESS FOR ERASE 


You have been denied erase access to the volume 
specified by the  pathname. Erase access is 
necessary to delete the file. 


114,NO ACCESS FOR CREATE 


You have been denied access to create or rename 
an entry in one of the directories specified in 
the pathname. 


115,NO ACCESS FOR DELETE 
You have been denied access to delete or rename 


an entry in one of the directories specified in 
the pathname. | 
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116,CANT DELETE NON-EMPTY DIRECTORY 


The pathname specified in a DELETE command 
identifies a directory, and that directory is 
not empty, that is, it still points to other 


volumes. Only empty directories can be deleted 
by a single file server DELETE command. To 


delete non-empty directories (i.e. subtrees) see 
the description of the TREEWALK utility in 
Chapter 4 of this manual. 


117,MEMORY FULL 


The file server has no space left for tables 
needed to complete your request. This does NOT 
refer to memory space in the user station. 


118,DISK FULL 


There is not enough contiguous space left on the 
disk unit to create the volume. The LIST 
command when used to display the root directory 
will give information about the space available 
on a disk unit. Example: "LIST /MAIN”. 


119,DIRECTORY FULL 


There is not enough space left to create more 
entries in the directory, and the directory 
cannot be expanded. Directories are 
automatically expanded as necesary to accomodate 
new entries. 


120, INTERNAL ERROR 


An internal error has been detected by the file 
server. Additional information is written on the 
console of the file server. That information and 
the circumstances surrounding the error should 
be transmitted to your support organization for 
diagnosis. The file server should be restarted 


A-16 ^" | 4/1/83 


ERRORS 


as soon as practical. 
121,UNINITIALIZED DISK 


The disk unit has not been initialized. All 
disks must be formatted and initialized using 
the file server FORMAT DISK utility; see the 
File Server Installation and Operation Manual. 


122,WRONG SOFTWARE VERSION 


The disk format is not compatible with version 
of the file server currently running. (This 


error cannot occur with any file servers so far 
released.) 


123,FILE ALREADY EXISTS 


The file you have asked to create, or the new 
name used in a RENAME command, already exists in 
the directory. 


124,DISK I/O ERROR, SUBCODES x,y 


A hardware I/O error was detected. The details 
of the error are described in the subcodes; for 
more information, see the table of I/O errors in 
Appendix A of the file server Installation and 
Operation manual. 


125,VERIFY FAILED (BAD MEMORY) 


All disk write operations are verified by 
reading back the recorded data and comparing it 


to the data stored in memory. This error 
indicates that the disk data did not compare 
correctly. It sometimes indicates a memory 


error in the file server, and not a disk error. 
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128,BAD UNIT NUMBER IN PATHNAME 


The first item after the initial slash in a 
pathname is a number, but it is not in the legal 
range for unit numbers (1 to 4). 


130,NEED PRIVATE PASSWORD FOR PROTECT 


In order to execute the PROTECT command for any 
volume, the private password must be specified 
in the pathname or as a default private 
password. The password must be specified 
whenvever the volume has a non-null private 
password, regardless of the access rights 
currently assigned to the volume. 


131,UNIT NAME NOT FOUND 


The name after the initial slash of a pathname 
is not the name of a disk unit currently 
recognized by the file server. You can also use 
the unit number in place of a name, if you 
wish. 


133,DISK NOT READY 


The disk unit specified is not ready. The one 
minute  warmup period after initial power up may 


not have elapsed. It may also indicate a 
controller or disk drive failure. 
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Appendix B 
Quick Reference List - File Server Commands 


CREATE pathname,type [,size](,sectors] 
| [;protection][,drive][,usage] 


- creates and optionally mounts a new virtual 
disk 


DELETE pathname 
- deletes a virtual disk from system 
HELP [command name] or ? [command name] 


- displays list of commands or syntax of 
specified command 


LIST [pathname] [,VERBOSE] [,NESTED] 


- lists entries in default or specified 
directory 


LOCK lockname [,usage] 


- locks "lockname" for exclusive (EXC) or 
shared (SHR) use 


— Default: EXC 
MOUNT pathname, drive [,usage] 


- establishes correspondence between a 
virtual disk and drive number 


OFF 


- initializes user station and downloads BOOT 
software 
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 PROTECT [pathname] [protection] 


modifies passwords or access rights for a 
virtual disk or directory 


RENAME oldpathname, newname 


renames specified FS file 


SET DIR pathname 


sets default directory 


SET [GRPPW=password] [PRVPW=password] 


SHOW 


Be? 


sets default group or private password 

DIR 

displays names of current default directory 
ID 

displays file server identification number 

INFO 

displays information about a virtual volume 
DIR 

displays name of current default directory 
LOCK [{lockname] 

lists all stations using specified lockname 
[ALL] LOCKS 

displays all locks set at own station or 


held in file server 
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[ALL] MOUNTS [pathname] 


gives information on virtual disks mounted 
on the file server 


PROTECTION [pathname] 


displays group, private and public access 
rights for virtual disk or directory 
addressed by pathname 


STATION 


displays own station number 


TIME 
displays current date and time 
TYPE Dd 


displays type of virtual disk mounted on 
drive d 


TYPES 


displays types of virtual disks mounted on 
drives 3-12 


VOLS 


displays names of system disk units 
currently operational 


TIMESTAMP 


returns encoded form of the current date 
and time 


UNLOCK lockname or UNLOCK ALL 
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- releases locked usage on a lockname or on 
all locknames currently held 


UNMOUNT Dd or UNMOUNT ALL 


- cancels previous mount(s) 


Parameters 


access rights: set of letters from RWECD (read, 
write, erase, create, and delete) 


drive: either Dd or .nd (for some local 
commands) where d=number between 1 and 11 


filepath: name[:password] [/filepath] 


lockname: name of lock (same restrictions as 
name ) 


name: name of disk unit, directory, or virtual 
disk. (1-15 characters; no commas, control 
characters, slashes, colons, returns or 
unprintable characters; imbedded blanks ok; 
first character any ok character) 


number: if decimal: between -32768 and 32767, 
inclusive if hex: between $0 and SFFFF, 
inclusive 


password: a secret word used to gain access to 
protected volumes. Same restrictions as 
name. except control characters allowed. 


pathname: /unitname/filepath or filepath (80 
characters max.) An initial slash indicates 
first field is a unit name; no initial slash 
indicates current default directory is to be 
prefixed to pathname. 
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protection: protect item [,protection] 


protect item: 

,» GRPPW=password 

» PRVPW=password 

»PUBACC=access rights (Default: R) 
,GRPACCsaccess rights (Default: PUBACC) 
,PRVACC-access rights (Default: varies) 


size: SIZE-number [.size-unit] 


size-unit: 
C: character----(1l byte) 
S: sector----(256 bytes) 
B: block-----(512 bytes) 
blank: block (512 bytes) 
Ko eem (1024 bytes) 
type: 
-B (binary) T=P (Apple // Pascal) 


T=C (Apple // CP/M) T=S (system) 


T-D (Apple // DOS) T=I (IBM PC DOS) 
T=T (text) T=Y (directory) 
T=U (IBM PC T=3 (Apple /// SOS) 


p-System Pascal) 


unitname: 1, 2, 3 or 4 [:password] or name 
[:password] 


usage: EXC(exclusive), SHR(shared), or 
UPD(update) RO(read only) or RW(read/write) 


Local NET Commands 


SHOW DRIVES 

SHOW FS 

SET .Nn[,.Nn,...][, VIRTUAL] [,SLOT n] 
SET FS [,SLOT n] [,STN $an] 

SPOOL TO device name/file name 

SPOOL OFF 
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Other NET Inputs 
drive: l-11 


drive-status: R, REAL, or V, VIRTUAL 
slot: default virtual slot 
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compatibility 3-9 
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Reader Comment Form 


This manual is one in a series that describes 
the use of the PLAN 4000 system. 


You are encouraged to use this form to 
communicate to Nestar . any problems or 
suggestions associated with the system. We would 
like your comments on improving the system 
itself, as well as on this documentation. 
Possible topics for comment are: clarity, 
accuracy, completeness, organization, coding, 
retrieval and legibility. 


No postage stamp is necessary if mailed within 
the U.S.A. 


Nestar installation location: 
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Address : 


Description of problem or suggestion: 


Please mail this form to : 
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2585 E. Bayshore Road 

Palo Alto, California 94303 
Attn: PUBLICATIONS DEPT. 
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